什么是swagger,一篇带你入门 | 您所在的位置:网站首页 › why swagger is used › 什么是swagger,一篇带你入门 |
一、前言
在前后端分离开发的过程中,前端和后端需要进行api对接进行交互,就需要一个api规范文档,方便前后端的交互,但api文档不能根据代码的变化发生实时动态的改变,这样后端修改了接口,前端不能及时获取最新的接口,导致调用出错,需要手动维护api文档,加大了开发的工作量和困难,而swagger的出现就是为了解决这一系列的问题。 二、swagger的概述swagger是一套基于OpenAPI规范构建的开源工具,使用RestApi 1、代码变,文档变 2、跨语言,支持多种语言 3、swagger-ui 呈现出来的是一份可交互式的API文档,可以直接在文档页面尝试API的调用 4、可以将文档规范导入相关工具(postman、soapui),这些工具将会为我们自动地创建自动化测试 补充: RestApi格式是根据请求的方式决定本次请求的一个操作,譬如:get-->读,post-->写(增、删、改),put-->修改,delete-->删除 OpenApi与语言无关,只是一种规范,可以使用yaml和json格式进行编写,这样更利于我们和机器进行阅读 swagger主要包含了以下三个部分: swagger editor:基于浏览器的编辑器,我们可以使用它编写我们OpenApi规范(yaml或者json配置) Swagger UI:他会将我们编写的OpenApi规范呈现为交互式的API文档,后文我将使用浏览器来查看并且操作我们的RestApi Swagger Codegen:它可以通过OpenApi规范定义的任何API生成服务器存根和客户端SDK来简化构建过程使用swagger就是把相关信息存储在它定义的描述文件里面(yml或json格式),再通过维护这个描述文件可以去更新接口文档,以及生成各端代码 三、springfox概述使用swagger时如果碰见版本更新迭代时,只需要更改swagger的描述文件即可,但是在频繁的更新项目版本时很多开发人员认为即使修改描述文件(yml或json文件)也是一定的工作负担,久而久之就直接修改代码,而不去修改描述文件了,这样基于描述文件生成接口文档也失去了意义。 Marty Pitt编写了一个基于spring的组件swagger-springmvc,Spring-fox就是根据这个组件发展而来的全新项目; Spring-fox是根据代码生成接口文档,所以正常的进行更新项目版本,修改代码即可,而不需要跟随修改描述文件(yml或json文件); spring-fox利用自身AOP特性,把swagger集成进来,底层还是Swagger,但是使用起来却方便很多,所以在实际开发中,都是直接使用spring-fox。 四、swagger的使用1、新建springboot项目 2、导入相关依赖 io.springfox springfox-swagger2 2.9.2 io.springfox springfox-swagger-ui 2.9.23、启动类中添加@EnableSwagger2注解 @enableSwagger2:是springfox提供的一个注解,代表swagger2相关技术开启,会扫描当前类所在包,以及子包中所有的类型中的注解,做swagger文档的定值 4、编写一个简单api接口 @RestController public class HelloController { @GetMapping("/get") public String get() { return "get"; } @PostMapping("/post") public String post() { return "post"; } @RequestMapping("/hello") public String hello() { return "hello"; } }5、启动项目,并在浏览器输入http://localhost:8080/swagger-ui.html进行swagger-ui界面访问 需求:开发和测试环境中开启swagger,其他环境不开启 @Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = Profiles.of("dev","test"); // 通过environment.acceptsProfiles()判断是否指定的环境中,是,则为true boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } // swagger文档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "https://iqiuq.gitee.io/qiuqblogs/", "[email protected]"); return new ApiInfo( "iqiuq swagger api", "演好自己人生的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }每个组就是一个docket实例,多个组就是创建多个docket的实例 @Configuration @EnableSwagger2 //开启swagger2 public class SwaggerConfig { // 创建swagger bean @Bean public Docket docket1(Environment environment) { // 配置swagger的docket的bean实例 Profiles profiles = Profiles.of("dev","test"); // 通过environment.acceptsProfiles()判断是否指定的环境中,是,则为true boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) // swagger信息 .apiInfo(apiInfo()) // 配置是否开启swagger,若为false,则浏览器不能访问 .enable(flag) // 配置组名 .groupName("iqiuq") .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } @Bean public Docket docket2(Environment environment) { Profiles profiles = Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .groupName("哈哈哈") .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } @Bean public Docket docket3(Environment environment) { Profiles profiles = Profiles.of("dev","test"); boolean flag = environment.acceptsProfiles(profiles); return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .enable(flag) .groupName("嘻嘻嘻") .select() .apis(RequestHandlerSelectors.basePackage("com.iqiuq.swaggerdemo.controller")) .paths(PathSelectors.regex("/hello")) .build(); } // swagger文档信息 public ApiInfo apiInfo() { Contact contact = new Contact( "iqiuq", "https://iqiuq.gitee.io/qiuqblogs/", "[email protected]"); return new ApiInfo( "iqiuq swagger api", "演好自己人生的剧本", "1.0", "urn:tos", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); }注意: 如果你使用的是swagger 3.0 你就需要使用 io.springfox springfox-swagger-ui 3.0.0 访问:http://localhost:8080/swagger-ui/index.html 就可以实现swagger-ui.html的访问 五、swagger常用注解swagger注解主要是用来给swagger生成的接口文档说明用的 5.1 @Api @Api:是类上注解,控制整个类生成接口信息的内容 tags:类的名称,可以有多个值,多个值表示多个副本,在UI视图中就显示几个控制器访问菜单 description:描述,已过时![]() ![]() ![]() ![]() @ApiResponses、@ApiResponse方法返回值的说明 @ApiResponses:方法返回对象的说明 @ApiResponse:每个参数的说明 code:数字,例如:300 message:信息,例如:”请求参数没填好" response:抛出异常的类 5.8 其他注解 @Authorization:声明要在资源或操作上使用的授权方案 @AuthorizationScope:描述OAuth2授权范围 @ResponseHeader:表示可以作为响应的一部分提供的标头 @ApiProperty:描述POJO对象中的属性值 @ApiError:接口错误所返回的信息 六、总结 我们可以通过swagger给一些比较难理解的属性或接口,增加注释信息 接口文档实时更新 可以在线测试 在正式发布的时候,关闭swagger,出于安全考虑,而且节省内存 |
CopyRight 2018-2019 实验室设备网 版权所有 |